/*
 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;
import java.util.*;

/**
 *
 * <p>这个接口强制每个实现它的类的对象排序。这个排序被称为类的自然排序，
 * 而且这个类的compareTo方法被称为它的自然排序方法。
 * 
 * <p>实现这个接口的对象的列表和数组能被自动排序，通过Collections.sort和Arrays.sort.
 * 实现这个接口的对象能够不需要指定一个Comparator，就能被用作SortedMap的key或者SortedSet的元素，
 * 
 * <p>对一个类C的自然排序被认为与equals方法一致，当且仅当：
 * 对于类C的每个对象e1和e2，e1.compareTo(e2) == 0和e1.equals(e2)有相同的结果。
 * 注意：null不是任何类的实例，并且e.compareTo(null)应该抛出一个NullPointerException，
 * 即使e.equals(null)返回false
 * 
 * <p>强烈建议（尽管不要求）自然排序与equals方法一致。
 * 这是因为没有显示的comparator的sorted set和sorted map在它们与
 * 自然排序与equals不一致的元素或者key，一起使用时，会显得很奇怪。
 * 尤其是，这样的sorted set和sorted map违反了set和map的通用约定，
 * 这个约定是根据equals方法定义的。
 * （因为map和set约定里面的key和元素根据equals是唯一的，
 * 但是sorted set和sorted map是根据compareTo方法定位的，而不是equals，
 * 所以如果不一致，会出现equals相同，但是同时出现的元素或者key）
 * 
 * <p>举个例子，如果向一个没有使用显示的comparator的sorted set添加两个元素a，b，
 * 并且  !a.equals(b) && a.compareTo(b) == 0（即equals不相同，compareTo相同），
 * 第二次添加会返回false（并且sorted set的大小不变），因为在sorted set的观点来看，a和b相同。
 * 
 * <p>事实上所有实现comparable接口的java核心类的自然排序都和equals方法一致。
 * 一个例外是java.math.BigDecimal，它的自然排序认为
 * 有着相同的值和不同的精度（例如4.0和4.00）是相同的，而它的equals方法认为两者不同。
 * 
 * <p>对于数学上小于的的，一个给定的类C定义的自然顺序的关系是：
 *    x.compareTo(y)<= 0
 * 整个的排序相同的关系是：
 *    x.compareTo(y) == 0
 * 
 * @param <T> 这个对象可能被比较的对象的类
 *
 * @author  Josh Bloch
 * @see java.util.Comparator
 * @since 1.2
 */
public interface Comparable<T> {
    /**
     * 
     * <p>为了排序，将这个对象与指定的对象进行比较。
     * 当这个对象小于，等于，大于指定对象时，返回一个小于0，等于0，大于0的int
     * 
     * <p>实现必须确保sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) 
     * （就是两者的符号必须相反或者同时=0）（sgn就是符号函数，结果是-1,0,1中的一个，代表着参数对应的符号）
     * 这隐含着如果y.compareTo(x)抛出一个异常，那么x.compareTo(y)必须抛出一个异常。
     * 
     * <p>实现必须也保证关系是传递的。
     * (x.compareTo(y)>0 && y.compareTo(z)>0) 隐含着x.compareTo(z)>0)
     * 
     * <p>最后实现必须保证x.compareTo(y)==0隐含着
     *  对于所有的z，sgn(x.compareTo(z)) == sgn(y.compareTo(z))
     *  
     * <p>强烈建议，但是不严格要求：(x.compareTo(y)==0) == (x.equals(y))。
     * 通常地来说，任何实现comparable接口但是违反了这个条件的类应该清楚地指出这个事实。
     * 推荐的语言是：注意：这个有自然排序的类与equals不一致。
     * Note: this class has a natural ordering that isinconsistent with equals.
     * 
     * <p>在上文的描述中，符号sgn，指出来数学上的正负号函数的作用，
     * 那就是根据表达式的值是负的，0，正的，返回-1,0,1
     *
     *
     * @param   o  被比较的对象
     * @return  当这个对象小于，等于，大于指定对象时，返回一个小于0，等于0，大于0的int
     *
     * @throws NullPointerException 如果指定对象为空
     * @throws ClassCastException 果指定对象的类防止它与这个对象进行比较
     */
    public int compareTo(T o);
}
